<h1>The annotation system</h1>

<p>
    In this chapter, we're going to talk about the annotations in <b>PHP</b>.
    For those who don't know what an annotation is, here's an example taken from
    the <b>Aspect PHP</b> library:
</p>

<div class="code">
    <code>
        /**<br />
        &nbsp;* The aspect container for Aspect PHP<br />
        &nbsp;*<br />
        &nbsp;* <b>@package</b>&nbsp;&nbsp;&nbsp;&nbsp;aspectPhp<br />
        &nbsp;* <b>@subpackage</b>&nbsp;lib<br />
        &nbsp;* <b>@author</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;gboisse<br />
        &nbsp;*/<br />
        class aspectContainer {<br />
    </code>
</div>

<p>
    Using annotations on our <b>PHP</b> classes means that we need to scan
    these classes. Let's start a new program (but keep the Foo and FooAspect
    classes!):
</p>

<div class="code">
    <code>
        require_once dirname(__FILE__) . '/path/to/lib/aspectAutoloader.php';<br />
        aspectAutoloader::register();<br />
        <br />
        require_once dirname(__FILE__) . '/Foo.class.php';<br />
        require_once dirname(__FILE__) . '/FooAspect.class.php';<br />
        <br />
        $aspectContainer = new aspectContainerBuilder('FooAspect');<br />
        <br />
        $foo = new aspectProxy(new Foo());<br />
        $foo->doSomeStuff('AOP');<br />
    </code>
</div>

<p class="notice">
    If you want to scan more than one aspect class, you can do it this way:
    <code>new aspectContainerBuilder('FooAspect', 'FooAspect2')</code> or this
    way:
    <code>new aspectContainerBuilder(array('FooAspect', 'FooAspect2'))</code>.
</p>

<p>
    Now, the container builder will automatically scan the FooAspect class for
    <b>AOP</b> annotations. Let's see how this works:
</p>

<div class="code">
    <code>
        <small>FooAspect.class.php</small><br />
        /**<br />
        &nbsp;* My foo aspect!<br />
        &nbsp;*<br />
        &nbsp;* <b>@aspect</b><br />
        &nbsp;*/<br />
        class FooAspect {<br />
        <br />
        &nbsp;&nbsp;&nbsp;&nbsp;/**<br />
        &nbsp;&nbsp;&nbsp;&nbsp; * <b>@before</b> method(Foo->doSomeStuff())<br />
        &nbsp;&nbsp;&nbsp;&nbsp; */<br />
        &nbsp;&nbsp;&nbsp;&nbsp;public function myBeforeAdvice() {<br />
        <br />
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;echo "I've been called before!\n";<br />
        &nbsp;&nbsp;&nbsp;&nbsp;}<br />
        <br />
        }<br />
    </code>
</div>

<p class="notice">
    The <u>@aspect</u> annotation on the class declaration indicates to
    <b>Aspect PHP</b> that this is an aspect class and that it contains some
    advices the library should scan.
</p>

<p>
    Here's the result of the execution:
</p>

<div class="code">
    <code>
        I've been called before!<br />
        I'm dealing with AOP!<br />
    </code>
</div>

<p>
    With very few code lines, we've been able to build an <b>AOP</b> environment
    for our application. Now let's take a look at the configuration
    possibilities given by <b>Aspect PHP</b>.
</p>